home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 2002 November
/
SGI Freeware 2002 November - Disc 2.iso
/
dist
/
fw_groff.idb
/
usr
/
freeware
/
catman
/
u_man
/
cat5
/
groff_tmac.Z
/
groff_tmac
Wrap
Text File
|
2002-04-08
|
10KB
|
224 lines
GROFF_TMAC(5) GROFF_TMAC(5)
NNAAMMEE
groff_tmac - macro files in the roff typesetting system
DDEESSCCRRIIPPTTIIOONN
The rrooffff(7) type-setting system provides a set of macro
packages suitable for special kinds of documents. Each
macro package stores its macros and definitions in a file
called the package's ttmmaacc ffiillee. The name is deduced from
`TTroff MMAACCros'.
The tmac files are normal roff source documents, except
that they usually contain only definitions and setup com
mands, but no text. All tmac files are kept in a single
or a small number of directories, the ttmmaacc directories.
NNAAMMIINNGG
In classical roff systems, there was a funny naming
scheme. If the name of a macro package started with `mm'
this letter was omitted, e.g., the macro package for the
man pages _m_a_n was called _a_n and its macro file _t_m_a_c_._a_n
(note that in recent versions of groff this file is called
_a_n_._t_m_a_c instead).
By a similar reasoning, macro packages that did not start
with an `mm' were often referred to by adding an `mm', e.g.,
the package corresponding to _t_m_a_c_._d_o_c was called _m_d_o_c
because the command-line for activating it reads
ttrrooffff --mm_d_o_c.
Actual versions of ggrrooffff(1) provide both naming schemes
for the inflicted macro packages, with and without the
leading `mm'. So in _g_r_o_f_f, the _m_a_n macro package may be
specified as
ggrrooffff --mm _m_a_n,
ggrrooffff --mm_a_n,
ggrrooffff --mm_m_a_n, or
ggrrooffff --mm _a_n.
The easiest way to find out which macro packages are
available on a system is to check the contents of the _t_m_a_c
directories. For example, a file called ttmmaacc.._a_n_y_t_h_i_n_g or
_a_n_y_t_h_i_n_g..ttmmaacc determines a macro package named _a_n_y_t_h_i_n_g.
In _g_r_o_f_f, most macro packages are described in man pages
called ggrrooffff__<<nnaammee>>(7), with a leading `mm' for the classi
cal packages.
IINNCCLLUUSSIIOONN
There are several ways to use a macro package in docu
ments. At run-time, the groff option --mm _n_a_m_e makes the
definitions in the macro file _n_a_m_e..ttmmaacc available as
described in the section NNAAMMIINNGG. If this file isn't
found, ttmmaacc.._n_a_m_e will be searched.
It is also possible to include the macro file into the
document by using the groff requests ..ssoo or ..mmssoo. For ..ssoo
the full filename of the macro file must be specified --
including the directory where it is kept. If the macro
file is stored in one of the tmac directories it is more
convenient to use ..mmssoo instead because it searches the
tmac path for the filename. Additionally, if the file
name to be included has the form _n_a_m_e..ttmmaacc and it isn't
found, ..mmssoo will try to open ttmmaacc.._n_a_m_e instead and vice
versa.
Note that in order to resolve the ..ssoo and ..mmssoo requests
the roff preprocessor ssooeelliimm must be called if the files
to be included needs preprocessing. This can be done
either directly by a pipeline on the command line or by
using the --ss option of ggrrooffff.
You can also supply the letter `ss' in the preprocessor
word as described in section CCOONNVVEENNTTIIOONN.
For example, suppose a macro file is stored as _/_u_s_r_/_f_r_e_e_
_w_a_r_e_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._1_7_._2_/_t_m_a_c_/_m_a_c_r_o_s_._t_m_a_c and is used in
some document called _d_o_c_u_._r_o_f_f.
At run-time, the formatter call for this is
ggrrooffff --mm _m_a_c_r_o_s _d_o_c_u_._r_o_f_f
To include the macro file directly in the document either
.mso macros.tmac
is used or
.so /usr/free
ware/share/groff/1.17.2/tmac/macros.tmac
In both cases, the formatter is called with
groff -s docu.roff
CCOONNVVEENNTTIIOONN
There is a convention that is supported by many modern
roff type-setters: the pprreepprroocceessssoorr wwoorrdd described in the
following.
If the first line in a document is a comment, the first
word (after the comment characters and a blank) consti
tutes the pprreepprroocceessssoorr wwoorrdd. That means that the letters
of this word are interpreted as abbreviations for those
preprocessor commands that should be run when formatting
the document. Mostly, only the letters corresponding to
the options for the preprocessors are recognized, `ee',
`GG', `gg', `pp', `RR', `ss', and `tt' (see rrooffff(7)).
Besides being a good reminder for the user, some format
ters (like the mmaann(1) program) are even able to automati
cally start the preprocessors specified in the preproces
sor word, but do not bet on this.
WWRRIITTIINNGG AA MMAACCRROO FFIILLEE
Writing a groff macro file is easy. Design a set of
macros, strings, registers, etc. Store them in a single
file. Documents that use the macros include this macro
file with the ..ssoo request as described in the IINNCCLLUUSSIIOONN
section.
To use the tmac functionality, call the macro file _w_h_a_t_
_e_v_e_r..ttmmaacc (or ttmmaacc.._w_h_a_t_e_v_e_r) and put it in some directory
of the tmac path, cf. section FFIILLEESS. Then documents can
include it with the ..mmssoo request or the ggrrooffff --mm option as
described in the IINNCCLLUUSSIIOONN section.
If your macros might be of general usage contact the groff
maintainers to have them included in the groff _c_o_n_t_r_i_b
source directory.
Some general guidelines might be helpful in writing
macros.
Double all functional backslashes, `\\' -> `\\\\'.
All printable backslashes must be written as `\\ee'.
Escape all dots, `..' -> `\\..'.
Make ample use of the non-printable character `\\&&' in
text parts, esp. before `\\' and at the beginning of a
line, but not before a delayed command.
Use the character `@@' in temporary variable names.
Test your macros for text and graphical devices, e.g.,
_l_a_t_i_n_1 and _p_s.
FFIILLEESS
All macro names must be named _n_a_m_e..ttmmaacc or ttmmaacc.._n_a_m_e to
use the tmac mechanism.
The macro files are kept in the ttmmaacc ddiirreeccttoorriieess, all of
which constitute the ttmmaacc ppaatthh..
The elements of the search path for macro files are (in
that order):
the directories specified with troff's resp. groff's
--MM command line option
the directories given in the GGRROOFFFF__TTMMAACC__PPAATTHH environ
ment variable
the current directory (only if in unsafe mode using
the --UU command line switch)
the home directory
a site-specific (platform-independent) directory, a
platform-specific directory, and the main tmac direc
tory:
/usr/freeware/share/groff/site-tmac
/usr/freeware/lib/groff/site-tmac
/usr/freeware/share/groff/1.17.2/tmac
EENNVVIIRROONNMMEENNTT
GGRROOFFFF__TTMMAACC__PPAATTHH
A colon separated list of additional tmac directo
ries in which to search for macro files. See the
previous section for a detailed description.
BBUUGGSS
The groff documentation is in evolution at the moment. It
is possible that small inconsistencies between different
documents exist temporarily.
AAUUTTHHOORR
This document is part of groff, the GNU roff distribution.
It was written by Bernd Warken <bwarken@mayn.de>.
It is distributed under the terms of the FDL (GNU Free
Documentation License) version 1.1 or later. You should
have received a copy of the FDL on your system, it is also
available on-line under
_<_h_t_t_p_:_/_/_w_w_w_._g_n_u_._o_r_g_/_c_o_p_y_l_e_f_t_/_f_d_l_._h_t_m_l_>.
SSEEEE AALLSSOO
The authoritative source of information for all details of
the groff system is the groff iinnffoo(1) file.
For a groff overview, see rrooffff(7) and the file _R_E_A_D_M_E in
the groff source package.
The groff tmac macro packages are ggrrooffff__mmaann(7),
ggrrooffff__mmwwwwww(7), ggrrooffff__mmddoocc(7), ggrrooffff__mmddoocc..ssaammpplleess(7),
ggrrooffff__mmee(7), ggrrooffff__mmmm(7), ggrrooffff__mmmmrrooffff(7), and
ggrrooffff__mmss(7).
The groff language is described in ggrrooffff(7) and the for
matters in ggrrooffff(1), ttrrooffff(1).
The Filesystem Hierarchy Standard (FHS) is available at
hhttttpp::////wwwwww..ppaatthhnnaammee..ccoomm//ffhhss//.
Groff Version 1.17.2 27 June 2001 GROFF_TMAC(5)